﻿// ===============================================================================
// IRouter.cs
// EOS Web Framework
// ===============================================================================
// Copyright (c) EOS Development Group. All rights reserved.
// ===============================================================================

namespace EOS.Framework.Contracts.Web.Routing
{
    using System;

    /// <summary>
    /// Finds the route, which match best to the current url. 
    /// </summary>
    public interface IRouter
    {
        /// <summary>
        /// Finds the best route from all matching routes in the "routes" parameter.
        /// Throws an NotRouteFoundException if there is no matching route.
        /// </summary>
        /// <param name="url">The URL. Cannot be null.</param>
        /// <param name="applicationPath">The application path. Cannot be null and must start with "/".</param>
        /// <returns>The best route.</returns>
        /// <example>
        /// 	<code>
        ///     router.Routes.Add(new Route("/Products/[id]", typeof(MyRouteHandler));
        ///     MatchingRoute matchingRoute = router.FindBestRoute(new Uri("http://www.mysite.de/Products/123"), "/");
        /// 
        ///     int id = int.Parse(matchingRoute.Parameters["id"]);
        /// </code>
        /// </example>
        /// <exception cref="ArgumentNullException">
        /// 	<para><paramref name="url"/> is NULL (Nothing in Visual Basic).</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="applicationPath"/> is NULL (Nothing in Visual Basic).</para>
        /// </exception>
        /// <exception cref="ArgumentException">
        /// 	<para><paramref name="applicationPath"/> is an invalid  ApplicationPath.</para>
        /// 	<para>- or -</para>
        /// 	<para><paramref name="url"/> is a string of length 0.</para></exception>
        /// <exception cref="NoRouteFoundException">If there is no matching route.</exception>
        /// <exception cref="InvalidRouteException">Thrown, if one of the routes is not valid.</exception>
        MatchingRoute FindBestRoute(Uri url, string applicationPath);

        /// <summary>
        /// Returns a list of all routes for this router.
        /// </summary>
        /// <value>The routes.</value>
        RouteDictionary Routes { get; }
    }
}
